CUBE CONNECT Edition Help

Control Statements

Most of the standard Matrix program statements are valid in the Generation program, and a few additional ones are available. Since the Generation program is a subset of the Matrix program, it is assumed that the user is familiar with the Matrix control statement set. Only the differences between the Matrix and Generation control statements are included in this section. For descriptions of other control statements see Control Statements.

Matrix statements not allowed in Generation:

Matrix keywords not allowed in Generation:

Generation statements not in Matrix:

BALANCE

This statement is used to specify how the trip ends are to be adjusted in the Phase=Adjust process. Keywords include:

This statement makes the adjustment process much simpler. Typically, most users adjust the Attraction totals to match the Production Totals.

BALANCE Keywords

  • A2P - |IP| - Specifies the purposes whose attraction totals are to be set to the production totals for that purpose.

  • NHB - |IP| - Specifies the purposes whose attraction totals are to be set to the production totals for that purpose, and then the productions are set equal to the attractions for each zone.

  • P2A - |IP| - Specifies the purposes whose production totals are to be set to the attraction totals for that purpose.

Example 

BALANCE A2P=1,2,4-7 NHB=3

COMP

Computes a variable, P/A row, or P/A row element. Keywords include:

  • VAR=expression (see Matrix COMP)

  • A[n][I]=expression

  • P[n][I]=expression

  • INCLUDE (see Matrix COMP)

  • EXCLUDE (see Matrix COMP)

The COMP statement is probably the most important of all the statements in the program. It is used to compute variable and P and A array values. The reader is advised to read "Introduction to Generation program" for information concerning the differences in array computation within the ILOOP and ADJUST phases. The major difference between the Generation and Matrix programs for COMP statements is in the use of P/A[] and MW[]. First of all, MW[] is not valid in the Generation program. Secondly, COMP P[]=, A[]=, and MW[]= expressions automatically imply a loop based upon J from 1 to zones in the Matrix program. While in the Generation program, when P[]= or A[]= is specified in the ILOOP phase, the J loops from I to I (a single iteration). Within the ADJUST phase, the J loops from 1 to zones. See COMP for details of COMP statements.

The COMP statement may contain INCLUDE and EXCLUDE to cause selective processing.

COMP Keywords

  • A[n][I] - |N| - Causes the program to solve the expression for each value of J. The result is stored in A[n][I]. If the second [] is not specified, it will default to I.

  • P[n][I] - |N| - Causes the program to solve the expression for each value of J. The result is stored in P[n][I]. If the second [] is not specified, it will default to I.

Expressions may contain the functions ATOT(#) and PTOT(#), which return the attraction and production totals for purpose #.

Example 

COMP P[1]= ZI.1.P1
COMP A[2]=0.90*ahbo
IF (I=38-49) P[1]=ZI.4.SPECIAL

FILEO

Generates trip-end records. Keywords and subkeywords include:

The PAO keyword is used to request that a file containing trip end records be written at the end of all stack processing. There may be multiple PAO specifications; each one should reference a different file. They will be processed in the order in which they appear in the input stream. The flexibility of the statement can allow records to be written in almost any format that other software systems might require. Within CUBE Voyager, the most likely place where this data would be read would be in any program that accepts ZDATI files; usually it should be written in a format such that the Distribution process can read it as the distribution trip ends. Although other data can be placed on these records, normally, the records should contain only the zone number (I), and the various trip ends such as P[1], a[1], etc.

For consistency, the PAO processing uses the CUBE Voyager General PRINT control statement processor. The PRINT processor is called one time for each zone in a loop where Z=1-Zones. The major difference between PAO and PRINT statement is that PAO specifies the output file by definition, and the FILE keyword is not allowed. Full documentation about the sub-keywords can be found in PRINT.

PAO can be optionally written as a DBF by setting DBF=T or to an MDB by designating the output MDB file name followed by a backslash and the element name.

FILEO Keywords

  • PAO - |KF10| - Name of a file where the formatted records are to be written.

  • PAO - CFORM - |S| - Format for following string list items. Normally, text variables will not be written to a PAO file.

  • PAO - DBF - |?| - Indicates if the output records are to written as a DBF file. This is off, unless turned on. If DBF=T is specified, the user may optionally name the variables to be written to the DBF records with the NAMES subkeyword. A maximum of 100 variables may be designated for single DBF.

    If the PAO keyword specifies an MDB file for the output, then DBF subkeyword should either not be specified or set to T. If DBF=F and PAO specifies an MDB file the program will fail.

  • PAO - FORM - |S| - Format for following numerical list items. FORM=20.2SLR is recommended if the Distribution program is going to read the file.

  • PAO - LIST - |S| - List of items to be formatted into the output buffer. P and A must be indexed; the zone index is automatically supplied as Z. In most cases, the only variables in the list will be Z, and expressions of P[n] and A[n] values. If any expressions are used, they should be enclosed within parenthesis, and should not contain any spaces or commas.

  • PAO - NAMES - |S| - Names to be assigned to the DBF variables. The names are positional (their indices refer to the positional location of the variables in the LIST). For example: 

    LIST=z,p1,p2,p3,a1,a2,a3,
DBF=T,NAMES=TAZ, WORKPROD, OTHERPROD,NHBPROD

    would set the names in the DBF for z,p1,p2,p3, respectively. Likewise: 

    NAMES[5]=WORKATTR, OTHERATTR, NHBATTR

    would set the names for a1,a2,a3.

    A name may not exceed 10 characters; it will be truncated, if designated as longer than 10. The routine does not check for duplicate names. Extraneous NAMES (that is, NAMES[11] in this example), are ignored. If there is no name specified for a variable, the program will use the variable name directly. If the LIST field is an expression, the program will use the first 10 alphanumeric digits, ignoring other characters. For example (VAR1+VAR2+VAR3) will be named VAR1VAR2VA.

  • PAO - PRINT - |?| - Indicates if the output records are to also be listed to the standard output. This is off, unless turned on.

Example 

PAO = OUTPUT.DAT, FORM=8.0,
LIST = Z(2) P[1] P[2] P[3] P[4] P[5] A[1] A[2] A[3] A[4] A[5] PRINT=N
PAO[2] = OUTPUT2.DAT, FORM=SL, Z P[1] A[1] P[2] A[2] (P[3]+P[4])
(A[3]+A[4])

PARAMETERS

Set general parameters. Keywords include:

PARAMETERS Keywords

  • MAXPURPS - |I| - Sets the number of P and A arrays to be allocated, and establishes an index boundary for P and A in COMP statements. The maximum value is 20, which the program defaults to, if the keyword is not specified. Setting this to a more realistic value will cause a less drain on computer memory.

  • ZONES - |I| - Establishes the number of zones to process. If ZONES is not specified, and the program has no other way to identify the appropriate number of zones, it will be set to 100.

Example 

ZONES=3000 MAXPURPS=5

PROCESS

Establishes phase blocks. Keywords include:

A user process phase stack is defined by a PROCESS statement that designates its beginning and an ENDPROCESS statement that designates its ending. To simplify coding, the PROCESS control word is not necessary; PHASE=name may be used directly. And, to further simplify coding, the ENDPROCESS statement is not necessary; the occurrence of another PROCESS statement acts as the ENDPROCESS statement. If ENDPROCESS is used, it may be coded as either ENDPROCESS or ENDPHASE. In the Generation program, normally, only the PHASE=ADJUST statement is all that is needed to differentiate between the normal ILOOP statements and the ADJUST statements that are used to balance the final Ps and As.

PROCESS Keywords

  • PHASE - |KS| - Names the phase stack. The control statements that follow it, until an ENDPROCESS statement or another PROCESS statement is encountered, will be executed when the phase is internally executed. Exception: Static statements, such as PARAMETERS, FILEI, FILEO, LOOKUP, are not processed as stack statements, even if they are located within a phase block. The following PHASE names may be specified:

    • ILOOP

    • ADJUST

  • ENDPHASE - |K| - Defines the end of the user control statements for a stack.

Example 

RUN PGM=GENERATION .
P[1]=....
.
.
PHASE=ADJUST
; the following statements are used to balance Ps and As
RUN PGM=GENERATION
.
PHASE=ILOOP
P[1]=....
.
PHASE=ADJUST
; the following statements are used to balance Ps and As

REPORT

Requests reports and establishes tracing. Keywords include:

REPORT Keywords

  • AC - |?| - Requests that the computed attractions be reported. This report precedes ADJUST processing.

  • A - |?| - Requests that the final attractions be reported. This report follows any ADJUST processing.

  • PC - |?| - Requests that the computed productions be reported. This report precedes ADJUST processing.

  • P - |?| - Requests that the final productions be reported. This report follows any ADJUST processing.

  • TRACE - |K?| - Controls the listing of the stack statements as they are processed.

Example 

REPORT AC=y A=y P=y
Parent topic: Generation